home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-Native.exe / {app} / include / elements / CEGUIScrollbar.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-07-16  |  15.6 KB  |  514 lines

  1. /************************************************************************
  2.     filename:     CEGUIScrollbar.h
  3.     created:    13/4/2004
  4.     author:        Paul D Turner
  5.     
  6.     purpose:    Interface to base class for Scrollbar widget
  7. *************************************************************************/
  8. /*************************************************************************
  9.     Crazy Eddie's GUI System (http://www.cegui.org.uk)
  10.     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
  11.  
  12.     This library is free software; you can redistribute it and/or
  13.     modify it under the terms of the GNU Lesser General Public
  14.     License as published by the Free Software Foundation; either
  15.     version 2.1 of the License, or (at your option) any later version.
  16.  
  17.     This library is distributed in the hope that it will be useful,
  18.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  19.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20.     Lesser General Public License for more details.
  21.  
  22.     You should have received a copy of the GNU Lesser General Public
  23.     License along with this library; if not, write to the Free Software
  24.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  25. *************************************************************************/
  26. #ifndef _CEGUIScrollbar_h_
  27. #define _CEGUIScrollbar_h_
  28.  
  29. #include "CEGUIBase.h"
  30. #include "CEGUIWindow.h"
  31. #include "elements/CEGUIScrollbarProperties.h"
  32.  
  33.  
  34. #if defined(_MSC_VER)
  35. #    pragma warning(push)
  36. #    pragma warning(disable : 4251)
  37. #endif
  38.  
  39.  
  40. // Start of CEGUI namespace section
  41. namespace CEGUI
  42. {
  43. /*!
  44. \brief
  45.     Base scroll bar class.
  46.  
  47.     This base class for scroll bars does not have any idea of direction - a derived class would
  48.     add whatever meaning is appropriate according to what that derived class
  49.     represents to the user.
  50. */
  51. class CEGUIEXPORT Scrollbar : public Window
  52. {
  53. public:
  54.     static const String EventNamespace;                //!< Namespace for global events
  55.  
  56.     /*************************************************************************
  57.         Event name constants
  58.     *************************************************************************/
  59.     static const String EventScrollPositionChanged;        //!< Name of the event fired when the scroll bar position value changes
  60.     static const String EventThumbTrackStarted;            //!< Name of the event fired when the user begins dragging the thumb.
  61.     static const String EventThumbTrackEnded;                //!< Name of the event fired when the user releases the thumb.
  62.     static const String EventScrollConfigChanged;            //!< Name of the event fired when the scroll bar configuration data changes.
  63.  
  64.  
  65.     /*************************************************************************
  66.         Accessor functions
  67.     *************************************************************************/
  68.     /*!
  69.     \brief
  70.         Return the size of the document or data.
  71.         
  72.         The document size should be thought of as the total size of the data that
  73.         is being scrolled through (the number of lines in a text file for example).
  74.  
  75.     \note
  76.         The returned value has no meaning within the Gui system, it is left up to the
  77.         application to assign appropriate values for the application specific use of
  78.         the scroll bar.
  79.  
  80.     \return
  81.         float value specifying the currently set document size.
  82.     */
  83.     float    getDocumentSize(void) const            {return d_documentSize;}
  84.  
  85.  
  86.     /*!
  87.     \brief
  88.         Return the page size for this scroll bar.
  89.         
  90.         The page size is typically the amount of data that can be displayed at one
  91.         time.  This value is also used when calculating the amount the position will
  92.         change when you click either side of the scroll bar thumb - the amount the
  93.         position changes will is (pageSize - overlapSize).
  94.  
  95.     \note
  96.         The returned value has no meaning within the Gui system, it is left up to the
  97.         application to assign appropriate values for the application specific use of
  98.         the scroll bar.
  99.  
  100.     \return
  101.         float value specifying the currently set page size.
  102.     */
  103.     float    getPageSize(void) const                {return d_pageSize;}
  104.  
  105.  
  106.     /*!
  107.     \brief
  108.         Return the step size for this scroll bar.
  109.         
  110.         The step size is typically a single unit of data that can be displayed, this is the
  111.         amount the position will change when you click either of the arrow buttons on the
  112.         scroll bar.  (this could be 1 for a single line of text, for example).
  113.  
  114.     \note
  115.         The returned value has no meaning within the Gui system, it is left up to the
  116.         application to assign appropriate values for the application specific use of
  117.         the scroll bar.
  118.  
  119.     \return
  120.         float value specifying the currently set step size.
  121.     */
  122.     float    getStepSize(void) const                {return d_stepSize;}
  123.  
  124.  
  125.     /*!
  126.     \brief
  127.         Return the overlap size for this scroll bar.
  128.         
  129.         The overlap size is the amount of data from the end of a 'page' that will
  130.         remain visible when the position is moved by a page.  This is usually used
  131.         so that the user keeps some context of where they were within the document's
  132.         data when jumping a page at a time.
  133.  
  134.     \note
  135.         The returned value has no meaning within the Gui system, it is left up to the
  136.         application to assign appropriate values for the application specific use of
  137.         the scroll bar.
  138.  
  139.     \return
  140.         float value specifying the currently set overlap size.
  141.     */
  142.     float    getOverlapSize(void) const            {return d_overlapSize;}
  143.  
  144.  
  145.     /*!
  146.     \brief
  147.         Return the current position of scroll bar within the document.
  148.  
  149.         The range of the scroll bar is from 0 to the size of the document minus the
  150.         size of a page (0 <= position <= (documentSize - pageSize)).
  151.  
  152.     \note
  153.         The returned value has no meaning within the Gui system, it is left up to the
  154.         application to assign appropriate values for the application specific use of
  155.         the scroll bar.
  156.  
  157.     \return
  158.         float value specifying the current position of the scroll bar within its
  159.         document.
  160.     */
  161.     float    getScrollPosition(void) const        {return d_position;}
  162.  
  163.  
  164.     /*************************************************************************
  165.         Manipulator Commands
  166.     *************************************************************************/
  167.     /*!
  168.     \brief
  169.         Initialises the Scrollbar object ready for use.
  170.  
  171.     \note
  172.         This must be called for every window created.  Normally this is handled automatically by the WindowFactory for each Window type.
  173.  
  174.     \return
  175.         Nothing
  176.     */
  177.     virtual void    initialise(void);
  178.  
  179.  
  180.     /*!
  181.     \brief
  182.         Set the size of the document or data.
  183.         
  184.         The document size should be thought of as the total size of the data that
  185.         is being scrolled through (the number of lines in a text file for example).
  186.  
  187.     \note
  188.         The value set has no meaning within the Gui system, it is left up to the
  189.         application to assign appropriate values for the application specific use of
  190.         the scroll bar.
  191.  
  192.     \param document_size
  193.         float value specifying the document size.
  194.  
  195.     \return
  196.         Nothing.
  197.     */
  198.     void    setDocumentSize(float document_size);
  199.  
  200.  
  201.     /*!
  202.     \brief
  203.         Set the page size for this scroll bar.
  204.         
  205.         The page size is typically the amount of data that can be displayed at one
  206.         time.  This value is also used when calculating the amount the position will
  207.         change when you click either side of the scroll bar thumb - the amount the
  208.         position changes will is (pageSize - overlapSize).
  209.  
  210.     \note
  211.         The value set has no meaning within the Gui system, it is left up to the
  212.         application to assign appropriate values for the application specific use of
  213.         the scroll bar.
  214.  
  215.     \param page_size
  216.         float value specifying the page size.
  217.  
  218.     \return
  219.         Nothing.
  220.     */
  221.     void    setPageSize(float page_size);
  222.  
  223.  
  224.     /*!
  225.     \brief
  226.         Set the step size for this scroll bar.
  227.         
  228.         The step size is typically a single unit of data that can be displayed, this is the
  229.         amount the position will change when you click either of the arrow buttons on the
  230.         scroll bar.  (this could be 1 for a single line of text, for example).
  231.  
  232.     \note
  233.         The value set has no meaning within the Gui system, it is left up to the
  234.         application to assign appropriate values for the application specific use of
  235.         the scroll bar.
  236.  
  237.     \param step_size
  238.         float value specifying the step size.
  239.  
  240.     \return
  241.         Nothing.
  242.     */
  243.     void    setStepSize(float step_size);
  244.  
  245.  
  246.     /*!
  247.     \brief
  248.         Set the overlap size for this scroll bar.
  249.         
  250.         The overlap size is the amount of data from the end of a 'page' that will
  251.         remain visible when the position is moved by a page.  This is usually used
  252.         so that the user keeps some context of where they were within the document's
  253.         data when jumping a page at a time.
  254.  
  255.     \note
  256.         The value set has no meaning within the Gui system, it is left up to the
  257.         application to assign appropriate values for the application specific use of
  258.         the scroll bar.
  259.  
  260.     \param overlap_size
  261.         float value specifying the overlap size.
  262.  
  263.     \return
  264.         Nothing.
  265.     */
  266.     void    setOverlapSize(float overlap_size);
  267.  
  268.  
  269.     /*!
  270.     \brief
  271.         Set the current position of scroll bar within the document.
  272.  
  273.         The range of the scroll bar is from 0 to the size of the document minus the
  274.         size of a page (0 <= position <= (documentSize - pageSize)), any attempt to
  275.         set the position outside this range will be adjusted so that it falls within
  276.         the legal range.
  277.  
  278.     \note
  279.         The returned value has no meaning within the Gui system, it is left up to the
  280.         application to assign appropriate values for the application specific use of
  281.         the scroll bar.
  282.  
  283.     \param position
  284.         float value specifying the position of the scroll bar within its
  285.         document.
  286.  
  287.     \return
  288.         Nothing.
  289.     */
  290.     void    setScrollPosition(float position);
  291.  
  292.  
  293.     /*************************************************************************
  294.         Construction / Destruction
  295.     *************************************************************************/
  296.     /*!
  297.     \brief
  298.         Constructor for Scrollbar objects
  299.     */
  300.     Scrollbar(const String& type, const String& name);
  301.  
  302.  
  303.     /*!
  304.     \brief
  305.         Destructor for Scrollbar objects
  306.     */
  307.     virtual ~Scrollbar(void);
  308.  
  309.  
  310. protected:
  311.     /*************************************************************************
  312.         Implementation Methods
  313.     *************************************************************************/
  314.     /*!
  315.     \brief
  316.         Add scroll bar specific events
  317.     */
  318.     void    addScrollbarEvents(void);
  319.  
  320.  
  321.     /*!
  322.     \brief
  323.         create a PushButton based widget to use as the increase button for this scroll bar.
  324.  
  325.     \param name
  326.         String holding the name that must be passed when creating the component widget.
  327.     */
  328.     virtual PushButton*    createIncreaseButton(const String& name) const        = 0;
  329.  
  330.  
  331.     /*!
  332.     \brief
  333.         create a PushButton based widget to use as the decrease button for this scroll bar.
  334.  
  335.     \param name
  336.         String holding the name that must be passed when creating the component widget.
  337.     */
  338.     virtual PushButton*    createDecreaseButton(const String& name) const        = 0;
  339.  
  340.  
  341.     /*!
  342.     \brief
  343.         create a Thumb based widget to use as the thumb for this scroll bar.
  344.  
  345.     \param name
  346.         String holding the name that must be passed when creating the component widget.
  347.     */
  348.     virtual Thumb*    createThumb(const String& name) const        = 0;
  349.  
  350.  
  351.     /*!
  352.     \brief
  353.         update the size and location of the thumb to properly represent the current state of the scroll bar
  354.     */
  355.     virtual void    updateThumb(void)    = 0;
  356.  
  357.  
  358.     /*!
  359.     \brief
  360.         return value that best represents current scroll bar position given the current location of the thumb.
  361.  
  362.     \return
  363.         float value that, given the thumb widget position, best represents the current position for the scroll bar.
  364.     */
  365.     virtual float    getValueFromThumb(void) const    = 0;
  366.  
  367.  
  368.     /*!
  369.     \brief
  370.         Given window location \a pt, return a value indicating what change should be 
  371.         made to the scroll bar.
  372.  
  373.     \param pt
  374.         Point object describing a pixel position in window space.
  375.  
  376.     \return
  377.         - -1 to indicate scroll bar position should be moved to a lower value.
  378.         -  0 to indicate scroll bar position should not be changed.
  379.         - +1 to indicate scroll bar position should be moved to a higher value.
  380.     */
  381.     virtual float    getAdjustDirectionFromPoint(const Point& pt) const    = 0;
  382.  
  383.  
  384.     /*!
  385.     \brief
  386.         handler function for when thumb moves.
  387.     */
  388.     bool    handleThumbMoved(const EventArgs& e);
  389.  
  390.  
  391.     /*!
  392.     \brief
  393.         handler function for when the increase button is clicked.
  394.     */
  395.     bool    handleIncreaseClicked(const EventArgs& e);
  396.  
  397.  
  398.     /*!
  399.     \brief
  400.         handler function for when the decrease button is clicked.
  401.     */
  402.     bool    handleDecreaseClicked(const EventArgs& e);
  403.  
  404.  
  405.     /*!
  406.     \brief
  407.         handler function for when thumb tracking begins
  408.     */
  409.     bool    handleThumbTrackStarted(const EventArgs& e);
  410.  
  411.  
  412.     /*!
  413.     \brief
  414.         handler function for when thumb tracking begins
  415.     */
  416.     bool    handleThumbTrackEnded(const EventArgs& e);
  417.  
  418.  
  419.     /*!
  420.     \brief
  421.         Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
  422.  
  423.     \param class_name
  424.         The class name that is to be checked.
  425.  
  426.     \return
  427.         true if this window was inherited from \a class_name. false if not.
  428.     */
  429.     virtual bool    testClassName_impl(const String& class_name) const
  430.     {
  431.         if (class_name==(const utf8*)"Scrollbar")    return true;
  432.         return Window::testClassName_impl(class_name);
  433.     }
  434.  
  435.  
  436.     /*************************************************************************
  437.         New event handlers for slider widget
  438.     *************************************************************************/
  439.     /*!
  440.     \brief
  441.         Handler triggered when the scroll position changes
  442.     */
  443.     virtual void    onScrollPositionChanged(WindowEventArgs& e);
  444.  
  445.  
  446.     /*!
  447.     \brief
  448.         Handler triggered when the user begins to drag the scroll bar thumb. 
  449.     */
  450.     virtual void    onThumbTrackStarted(WindowEventArgs& e);
  451.  
  452.  
  453.     /*!
  454.     \brief
  455.         Handler triggered when the scroll bar thumb is released
  456.     */
  457.     virtual void    onThumbTrackEnded(WindowEventArgs& e);
  458.  
  459.  
  460.     /*!
  461.     \brief
  462.         Handler triggered when the scroll bar data configuration changes
  463.     */
  464.     virtual void    onScrollConfigChanged(WindowEventArgs& e);
  465.  
  466.  
  467.     /*************************************************************************
  468.         Overridden event handlers
  469.     *************************************************************************/
  470.     virtual void    onMouseButtonDown(MouseEventArgs& e);
  471.     virtual    void    onMouseWheel(MouseEventArgs& e);
  472.  
  473.  
  474.     /*************************************************************************
  475.         Implementation Data
  476.     *************************************************************************/
  477.     float    d_documentSize;        //!< The size of the document / data being scrolled thorugh.
  478.     float    d_pageSize;            //!< The size of a single 'page' of data.
  479.     float    d_stepSize;            //!< Step size used for increase / decrease button clicks.
  480.     float    d_overlapSize;        //!< Amount of overlap when jumping by a page.
  481.     float    d_position;            //!< Current scroll position.
  482.  
  483.     // Pointers to the controls that make up the scroll bar
  484.     Thumb*        d_thumb;        //!< widget used to represent the 'thumb' of the scroll bar.
  485.     PushButton*    d_increase;        //!< Widget used for the increase button of the scroll bar.
  486.     PushButton*    d_decrease;        //!< Widget used for the decrease button of the scroll bar.
  487.  
  488.  
  489. private:
  490.     /*************************************************************************
  491.         Static Properties for this class
  492.     *************************************************************************/
  493.     static ScrollbarProperties::DocumentSize    d_documentSizeProperty;
  494.     static ScrollbarProperties::PageSize        d_pageSizeProperty;
  495.     static ScrollbarProperties::StepSize        d_stepSizeProperty;
  496.     static ScrollbarProperties::OverlapSize        d_overlapSizeProperty;
  497.     static ScrollbarProperties::ScrollPosition    d_scrollPositionProperty;
  498.  
  499.  
  500.     /*************************************************************************
  501.         Private methods
  502.     *************************************************************************/
  503.     void    addScrollbarProperties(void);
  504. };
  505.  
  506.  
  507. } // End of  CEGUI namespace section
  508.  
  509. #if defined(_MSC_VER)
  510. #    pragma warning(pop)
  511. #endif
  512.  
  513. #endif    // end of guard _CEGUIScrollbar_h_
  514.